<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>cocoOS: docMessages.h File Reference</title>

<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>


</head>
<body>
<div id="top"><!-- do not remove this div! -->


<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  
  
  <td style="padding-left: 0.5em;">
   <div id="projectname">cocoOS
   &#160;<span id="projectnumber">3.0.0</span>
   </div>
   
  </td>
  
  
  
 </tr>
 </tbody>
</table>
</div>

<!-- Generated by Doxygen 1.7.6 -->
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li class="current"><a href="files.html"><span>Files</span></a></li>
    </ul>
  </div>
  <div id="navrow2" class="tabs2">
    <ul class="tablist">
      <li><a href="files.html"><span>File&#160;List</span></a></li>
      <li><a href="globals.html"><span>Globals</span></a></li>
    </ul>
  </div>
</div>
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
  initNavTree('doc_messages_8h.html','');
</script>
<div id="doc-content">
<div class="header">
  <div class="headertitle">
<div class="title">docMessages.h File Reference</div>  </div>
</div>
<div class="contents">
<hr/><a name="details" id="details"></a><h2>Detailed Description</h2>
<div class="textblock"><p>If the tasks in an application needs to exchange more information than just simple events, they can use messages. The base type for messages is the Msg_t, which is a struct with three members: </p>
<div class="fragment"><pre class="fragment"><span class="keyword">typedef</span> <span class="keyword">struct </span>{
    uint8_t signal;
    uint8_t reserved;
    uint16_t delay;
} Msg_t;
</pre></div><p>The first member, <em>signal</em>, is used for message indentification by the application.<br/>
 <em>reserved</em> is an alignment byte.<br/>
 <em>delay</em> is used by the kernel when sending delayed messages. Should not be accessed by the application.</p>
<p>From this base type, the application can create its own message types containing the members needed: </p>
<div class="fragment"><pre class="fragment"><span class="keyword">enum</span> {
    LED_ON_SIG,
    LED_OFF_SIG
};

<span class="keyword">typedef</span> <span class="keyword">struct </span>{
    Msg_t super;    <span class="comment">/* All application defined message types should inherit from the Msg_t */</span>
    uint8_t led;
} LedMsg_t;

<span class="keywordtype">void</span> task( <span class="keywordtype">void</span> ) {
    <span class="keyword">static</span> LedMsg_t ledMsg;

    ledMsg.super.signal = LED_ON_SIG;
    ledMsg.led = 0;

    <a class="code" href="os__appl_a_p_i_8h.html#ac19d6a48c1cb673360ae220aaf2a9d53">task_open</a>();
    ...
    <a class="code" href="os__appl_a_p_i_8h.html#a7912af19af4a033fd9caf27879614945">task_close</a>();
}
</pre></div><p><b>Message passing</b> <br/>
 Messages are passed between tasks by copying the message into a message queue. The posted message must be of the same type that are held by the message queue. The application must allocate space for this message queue and pass the address of the queue, the queue length and the message size when creating the task: </p>
<div class="fragment"><pre class="fragment"><span class="keyword">static</span> LedMsg_t msgpool[ Q_SIZE ];

<span class="keywordtype">int</span> main(<span class="keywordtype">void</span>) {
    <a class="code" href="os__appl_a_p_i_8h.html#adb53dc7146d0e27f8ac2675f62dd6124">task_create</a>( task, prio, msgpool, Q_SIZE, <span class="keyword">sizeof</span>(LedMsg_t) );
}
</pre></div><p><b>Mutual exclusion and synchronization</b> <br/>
 For each message queue, cocoOS creates a binary semaphore and an event intended to be used for mutual exclusion and synchronization. <br/>
 Before accessing the queue for either posting or receiving a message, the semaphore should be aquired using <a class="el" href="os__appl_a_p_i_8h.html#ae66288422355db64c18c53676e53eddb">msg_q_get()</a>. If the semaphore is already taken by another task, the task will be put into the waiting state until the semaphore is released. <br/>
 <br/>
</p>
<p>The event associated with a message queue is automatically signaled when the queue contents changes, i.e. a message is posted to or removed from the queue. A task will be put to wait for the event when a message queue was full or empty when trying to post or receive a message respectively. Then when the event is signalled, the task makes a new post/receive retry to the message queue. <br/>
 When a message has been received or posted, the queue semaphore must be released using a call to <a class="el" href="os__appl_a_p_i_8h.html#adc67691f29549315143cc60ff43e2306">msg_q_give()</a>. <br/>
</p>
<p><b>Posting messages</b> <br/>
 A message can be posted immediately into another task's message queue by using <a class="el" href="os__appl_a_p_i_8h.html#a017f7852a4fe5b619c58a9adf3d57bd7">msg_post()</a>. The message will be placed in the receiving task's message queue fifo and will be processed as soon as possible. With <a class="el" href="os__appl_a_p_i_8h.html#abaae70bdc9e52397b8cb61698d850cda">msg_post_in()</a> it is possible to specify a delay before the message will be delivered to the receiving task. </p>
<div class="fragment"><pre class="fragment"><span class="keyword">static</span> Msg_t msgpool[ 16 ];

<span class="keywordtype">int</span> main(<span class="keywordtype">void</span>)
{
        ...
    <a class="code" href="os__appl_a_p_i_8h.html#adb53dc7146d0e27f8ac2675f62dd6124">task_create</a>( task1, 1, NULL, 0, 0 );
    <a class="code" href="os__appl_a_p_i_8h.html#adb53dc7146d0e27f8ac2675f62dd6124">task_create</a>( task2, 2, msgpool, 16, <span class="keyword">sizeof</span>(Msg_t) );
    <a class="code" href="os__appl_a_p_i_8h.html#adb53dc7146d0e27f8ac2675f62dd6124">task_create</a>( task3, 3, NULL, 0, 0 );
    ...
    <a class="code" href="os__appl_a_p_i_8h.html#a19c7111cf2121a69331d99dabe3e9df0">os_start</a>();
    <span class="keywordflow">return</span> 0;
}


<span class="keyword">static</span> <span class="keywordtype">void</span> task1(<span class="keywordtype">void</span>) {
    <span class="keyword">static</span> Msg_t msg;

    msg.signal = 10MS_SIG;
    
    <a class="code" href="os__appl_a_p_i_8h.html#ac19d6a48c1cb673360ae220aaf2a9d53">task_open</a>();
    
    <span class="keywordflow">for</span> (;;) {
        
        <a class="code" href="os__appl_a_p_i_8h.html#ad8232a672a6d4f3a4532bea410a0b1ef">task_wait</a>( 10 );
        
        <span class="comment">/* Always aquire the message queue semaphore */</span>
        <a class="code" href="os__appl_a_p_i_8h.html#ae66288422355db64c18c53676e53eddb">msg_q_get</a>( task2 );

        <span class="comment">/* Post the message into task2&#39;s queue */</span>
        <a class="code" href="os__appl_a_p_i_8h.html#a017f7852a4fe5b619c58a9adf3d57bd7">msg_post</a>( task2, msg) );

        <span class="comment">/* Release the semaphore */</span>
        <a class="code" href="os__appl_a_p_i_8h.html#adc67691f29549315143cc60ff43e2306">msg_q_give</a>( task2 );  
    }

    <a class="code" href="os__appl_a_p_i_8h.html#a7912af19af4a033fd9caf27879614945">task_close</a>();

}


<span class="keyword">static</span> <span class="keywordtype">void</span> task3(<span class="keywordtype">void</span>) {
    <span class="keyword">static</span> Msg_t msg;

    msg.signal = BUTTON_SIG;
    
    <a class="code" href="os__appl_a_p_i_8h.html#ac19d6a48c1cb673360ae220aaf2a9d53">task_open</a>();
    
    <span class="keywordflow">for</span> (;;) {
        
        <a class="code" href="os__appl_a_p_i_8h.html#a576b2326d068ab852846ee612c7b954c">event_wait</a>( buttonEvt );
        
        <span class="comment">/* Always aquire the message queue semaphore */</span>
        <a class="code" href="os__appl_a_p_i_8h.html#ae66288422355db64c18c53676e53eddb">msg_q_get</a>( task2 );

        <span class="comment">/* Post the message into task2&#39;s queue with 1000 ticks delay */</span>
        <a class="code" href="os__appl_a_p_i_8h.html#abaae70bdc9e52397b8cb61698d850cda">msg_post_in</a>( task2, msg, 1000) );

        <span class="comment">/* Release the semaphore */</span>
        <a class="code" href="os__appl_a_p_i_8h.html#adc67691f29549315143cc60ff43e2306">msg_q_give</a>( task2 );  
    }

    <a class="code" href="os__appl_a_p_i_8h.html#a7912af19af4a033fd9caf27879614945">task_close</a>();

}
</pre></div><p><b>Receiving messages</b><br/>
 Receiving messages is done in the same manner as posting messages, but using <a class="el" href="os__appl_a_p_i_8h.html#ac09ba62464c1027ee133b7a6878bfa83">msg_receive()</a> instead. <br/>
 <br/>
 </p>
<div class="fragment"><pre class="fragment"><span class="keyword">static</span> Msg_t msgpool[ 16 ];

<span class="keywordtype">int</span> main(<span class="keywordtype">void</span>)
{
        ...
    <a class="code" href="os__appl_a_p_i_8h.html#adb53dc7146d0e27f8ac2675f62dd6124">task_create</a>( task1, 1, NULL, 0, 0 );
    <a class="code" href="os__appl_a_p_i_8h.html#adb53dc7146d0e27f8ac2675f62dd6124">task_create</a>( task2, 2, msgpool, 16, <span class="keyword">sizeof</span>(Msg_t) );
    ...
    <a class="code" href="os__appl_a_p_i_8h.html#a19c7111cf2121a69331d99dabe3e9df0">os_start</a>();
    <span class="keywordflow">return</span> 0;
}


<span class="keyword">static</span> <span class="keywordtype">void</span> task2(<span class="keywordtype">void</span>) {
    <span class="keyword">static</span> Msg_t msg;
    
    <a class="code" href="os__appl_a_p_i_8h.html#ac19d6a48c1cb673360ae220aaf2a9d53">task_open</a>();
    
    <span class="keywordflow">for</span> (;;) {
        
        <span class="comment">/* Always aquire the message queue semaphore */</span>
        <a class="code" href="os__appl_a_p_i_8h.html#ae66288422355db64c18c53676e53eddb">msg_q_get</a>( task2 );

        <span class="comment">/* Wait for a message */</span>
        <a class="code" href="os__appl_a_p_i_8h.html#ac09ba62464c1027ee133b7a6878bfa83">msg_receive</a>( task2, &amp;msg) );

        <span class="comment">/* Release the semaphore */</span>
        <a class="code" href="os__appl_a_p_i_8h.html#adc67691f29549315143cc60ff43e2306">msg_q_give</a>( task2 );  
    }

    <a class="code" href="os__appl_a_p_i_8h.html#a7912af19af4a033fd9caf27879614945">task_close</a>();

}
</pre></div><p><b>Periodic messages</b><br/>
 A message can also be setup to be delivered periodically to its receiver with <a class="el" href="os__appl_a_p_i_8h.html#a1d4ff9caf0714728a46973fe7ef76868">msg_post_every()</a>. This message will be put into the message queue as a usual delayed message posted with the <a class="el" href="os__appl_a_p_i_8h.html#abaae70bdc9e52397b8cb61698d850cda">msg_post_in()</a> method. When the message delay expires, the message is delivered to the task and reposted to the queue automatically with the timer reloaded. A posted periodic message can not be stopped, it will be delivered periodically forever.</p>
<p><b>Message API</b><br/>
 The message API consists of the following macros and functions:<br/>
</p>
<ul>
<li><a class="el" href="os__appl_a_p_i_8h.html#a017f7852a4fe5b619c58a9adf3d57bd7">msg_post()</a></li>
<li><a class="el" href="os__appl_a_p_i_8h.html#abaae70bdc9e52397b8cb61698d850cda">msg_post_in()</a></li>
<li><a class="el" href="os__appl_a_p_i_8h.html#ac09ba62464c1027ee133b7a6878bfa83">msg_receive()</a></li>
<li><a class="el" href="os__appl_a_p_i_8h.html#ae66288422355db64c18c53676e53eddb">msg_q_get()</a></li>
<li><a class="el" href="os__appl_a_p_i_8h.html#adc67691f29549315143cc60ff43e2306">msg_q_give()</a></li>
<li><a class="el" href="os__appl_a_p_i_8h.html#a1d4ff9caf0714728a46973fe7ef76868">msg_post_every()</a> </li>
</ul>
</div></div>
</div>
  <div id="nav-path" class="navpath">
    <ul>
      <li class="navelem"><a class="el" href="doc_messages_8h.html">docMessages.h</a>      </li>

    <li class="footer">Generated on Thu Dec 22 2011 21:14:42 for cocoOS by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.7.6 </li>
   </ul>
 </div>


</body>
</html>
